[% setvar title Inline Comments for Perl. %]
<div id="archive-notice">
    <h3>This file is part of the Perl 6 Archive</h3>
    <p>To see what is currently happening visit <a href="http://www.perl6.org/">http://www.perl6.org/</a></p>
</div>
<div class='pod'>
<a name='TITLE'></a><h1>TITLE</h1>
<p>Inline Comments for Perl.</p>
<a name='VERSION'></a><h1>VERSION</h1>
<pre>  Maintainer: Glenn Linderman &lt;<a href='mailto:glenn@linderman.com'>glenn@linderman.com</a>&gt;
  Date: 14 Aug 2000
  Last Modified: 14 Sep 2000
  Mailing List: <a href='mailto:perl6-language@perl.org'>perl6-language@perl.org</a>
  Number: 102
  Version: 2
  Status: Frozen</pre>
<a name='ABSTRACT'></a><h1>ABSTRACT</h1>
<p>Unlike  many programming  languages Perl  does not  currently implement
inline  comments. This  can be  confusing/tedious to  programmers. This
could  be solved by  adding a  syntax to  Perl 6  that would  allow for
inline comments.</p>
<a name='DESCRIPTION'></a><h1>DESCRIPTION</h1>
<p>Comments are  important to  programmers as a  way of  documenting their
code and  for debugging purposes.  Perl's comment  syntax requires that
comments can only be placed at the end of a line, or on a separate line
(or lines).  Sometimes it is desirable to place a comment (or comments)
within a line.</p>
<p>Perl  currently  uses  the  &quot;#&quot;  character as  an  end-of-line  comment
introducer (as  do many other  scripting languages).  RFC  5 (multiline
comments) suggests as a possible  promising syntax an introducer of the
form  &quot;#&lt;&lt;TOKEN&quot;, combining the  perl concepts  of &quot;comment&quot;  and &quot;here
document&quot; for multiline comments.</p>
<p>It is felt  that an inline comment syntax  should leverage the existing
Perl  comment concept  (&quot;#&quot;  introducer) and  that  the introducer  and
terminator should look like a matched pair for ease of understanding.</p>
<a name='Ideas from other languages'></a><h2>Ideas from other languages</h2>
<p>C/C++  use  &quot;/*&quot; and  &quot;*/&quot;  as  introducer/terminator  for in-line  and
multi-line  comments.  A  different syntax  was introduced  in  C++ for
end-of-line comments: &quot;//&quot;.</p>
<p>Pascal  uses &quot;(*&quot;  and  &quot;*) as  introducer/terminator  for in-line  and
multi-line  comments.   It  has  similar  difficulties  as  C/C++  with
commenting out blocks of code.</p>
<p>Forth  uses  &quot;(&quot;  and  &quot;)&quot;  as introducer/terminator  for  in-line  and
multi-line comments, and &quot;\&quot; for end-of-line comments.</p>
<p>Basic doesn't support in-line or multi-line comments.</p>
<p>All the languages  that use the same syntax  for in-line and multi-line
comments suffer  from confusion  when a multi-line  comment is  used to
comment   out   a   block   of  code   containing   in-line   comments.
Implementations have historically varied  within the language on how to
handle that situation.</p>
<a name='Ideas for perl'></a><h2>Ideas for perl</h2>
<p>An  idea that produces  a paired  feeling would  be to  use one  of the
paired character pairs, as in &quot;#&lt;&quot;  and &quot;&gt;#&quot;.  I like this one best, of
the three paired character  possibilities (&quot;&lt;&gt;&quot;, &quot;()&quot;, &quot;{}&quot;) because it
is  more  closely  related  to  the  &quot;#&lt;&lt;TOKEN&quot;  syntax  suggested  for
multi-line comments by RFC 5,  thus also achieving a more Perlish feel,
when combined with that syntax.</p>
<p>An idea with obvious appeal to C/C++/Pascal programmers would be to use
&quot;#*&quot; as the introducer, and &quot;*# as the terminator.  This would probably
work as good as any.</p>
<a name='Compatibility considerations'></a><h2>Compatibility considerations</h2>
<p>Because  &quot;#&quot; has been  used to  mean comment,  it seems  that something
related to &quot;#&quot; should continue to be used to mean comment.</p>
<p>Use of a bare &quot;#&quot; as  an in-line comment terminator would break lots of
existing  practice, where  people have  used  a variant  number of  &quot;#&quot;
characters to  introduce comments of more  or less importance,  or as a
way of achieving &quot;pretty&quot; multi-line comments (example of such next)</p>
<p>#################################
## This is a stand-out comment ##
#################################</p>
<p>Hence it seems  some other character should be combined  with &quot;#&quot; as an
in-line comment introducer, and used  in reverse order (per practice in
other languages) as the comment terminator.</p>
<p>Because historically there is nothing to prevent a sequence such as the
following:</p>
<pre>   code #&lt; this is an end-of-line &gt;# comment</pre>
<p>from  appearing, this  suggestion  is not  100%  compatible with  perl5
syntax.  However,  such a sequence  is relatively unlikely:  I've never
seen one in any Perl code  I've perused.  By limiting this construct to
less than a single line, it limits the boundaries of confusion: if &quot;#&lt;&quot;
is found with the intended meaning of an end-of-line comment introducer
followed by a  &quot;&lt;&quot; character, the highly probable  lack of the sequence
&quot;&gt;#&quot; within  the same  line can  be diagnosed with  a warning  or error
identifying exactly the line involved.</p>
<a name='Discussion in perl6-language and perl6-language-mlc'></a><h2>Discussion in perl6-language and perl6-language-mlc</h2>
<p>There was some discussion of in-line comments in the perl6-language and
perl6-language-mlc  lists.   There  wasn't  a consensus  reached.   The
competing suggestion  for in-line comments was  to define &quot;qc/comment/&quot;
as  a syntax that  evaporates.  I  don't like  that syntax,  because it
looks more like code than comment,  and doesn't stand out to the eye as
a comment when mixed within code:</p>
<pre>   $foo = qw/foo bar/ qc/eat me/;</pre>
<p>It is not clear whether such syntax would be easily readable within all
forms of expressions, without operators, as shown in the above example,
vs</p>
<pre>   $foo = qw/foo bar/ #&lt;eat me&gt;#;</pre>
<a name='IMPLEMENTATION'></a><h1>IMPLEMENTATION</h1>
<p>Should be straightforward in the Perl parser/lexer.</p>
<a name='REFERENCES'></a><h1>REFERENCES</h1>
<p>RFC 5: Multiline Comments for Perl.</p>
<p>Discussion archives of the perl-language and perl-language-mlc lists</p>
</div>
